.TH PLOTCHANGELOG 1 "Debian Utilities" "DEBIAN" \" -*- nroff -*-
.SH NAME
plotchangelog \- graph Debian changelogs
.SH SYNOPSIS
.B plotchangelog
.I "\fR[\fPoptions\fR]\fP changelog \fR...\fP"
.SH "DESCRIPTION"
.BR plotchangelog
is a tool to aid in visualizing a Debian \fIchangelog\fR. The changelogs are
graphed with
.BR gnuplot (1)
, with the X axis of the graph denoting time of release and the Y axis
denoting the Debian version number of the package. Each individual release
of the package is represented by a point, and the points are color coded to
indicate who released that version of the package. The upstream version
number of the package can also be labeled on the graph.
.PP
Alternatively, the Y axis can be configured to display the size of the
changelog entry for each new version. Or it can be configured to display
approximately how many bugs were fixed for each new version.
.PP
Note that if the package is a Debian-specific package, the entire package
version will be used for the Y axis. This does not always work perfectly.
.PP
.SH "READING THE GRAPH"
The general outline of a package's
graph is typically a series of peaks, starting at 1, going up to n, and then
returning abruptly to 1. The higher the peaks, the more releases the
maintainer made between new upstream versions of the package. If a package
is Debian-only, it's graph will just grow upwards without ever falling
(although a bug in this program may cause it to fall sometimes, if the
version number goes from say, 0.9 to say, 0.10 - this is interpreted wrong...)
.PP
If the graph dips below 1, someone made a NMU of the package and upgraded it
to a new upstream version, thus setting the Debian version to 0. NMU's in
general appear as fractional points like 1.1, 2.1, etc. A NMU can also be
easily detected by looking at the points that represent which maintainer
uploaded the package -- a solitary point of a different type than the points
before and after it is typically a NMU.
.PP
It's also easy to tell by looking at the points when a package changes
maintainers.
.SH OPTIONS
.TP
.B \-l\fR, \fP\-\-linecount
Instead of using the Debian version number as the Y axis, use the number of
lines in the changelog entry for each version.  Cannot be used
together with
.BR \-\-bugcount .
.TP
.B \-b\fR, \fP\-\-bugcount
Instead of using the Debian version number as the Y axis, use the number of
bugs that were closed by each changelog entry. Note that this number is
obtained by searching for "#dddd" in the changelog, and so it may be
inaccurate.  Cannot be used together with
.BR \-\-linecount .
.TP
.B \-c\fR, \fP\-\-cumulative
When used together with either
.B \-\-bugcount
or
.BR \-\-linecount ,
graphs the cumulative count rather than the count in each individual
changelog entry.
.TP
.B \-v\fR, \fP\-\-no-version
Do not show upstream version labels. Useful if the graph gets too crowded.
.TP
.B \-m, \-\-no-maint
Do not differentiate between different maintainers of the package.
.TP
.B \-s file\fR, \fP\-\-save=\fIfile
Save the graph to \fIfile\fR in PostScript format instead of immediately
displaying it.
.TP
.B \-u\fR, \fP\-\-urgency
Use larger points when displaying higher-urgency package uploads.
.TP
.B \-\-verbose
Output the gnuplot script that is fed into gnuplot (for debugging purposes).
.TP
.B \-g\fIcommands\fR, \fB\-\-gnuplot=\fIcommands
This allows you to insert
.BR gnuplot (1)
commands into the gnuplot script that is used to generate the graph. The
commands are placed after all initialization but before the final \fBplot\fR
command. This can be used to override the default look provided by this
program in arbitrary ways. You can also use things like
"set terminal png color"
to change the output file type, which is useful in conjunction with
the \-s option.
.TP
.B \-\-help
Show a usage summary.
.TP
.B \-\-version
Display version, author and copyright information.
.TP
.B \-\-noconf\fR, \fP\-\-no-conf
Do not read any configuration files (see below).
.TP
.I changelog \fR...
The \fIchangelog\fR files to graph. If multiple files are specified they will all
be displayed on the same graph. The files may be compressed with gzip. Any
text in them that is not in Debian changelog format will be ignored.
.SH "CONFIGURATION VARIABLES"
The two configuration files \fI/etc/devscripts.conf\fR and
\fI~/.devscripts\fR are sourced by a shell in that order to set
configuration variables.  The \fB\-\-no\-conf\fR option can be used to
prevent reading these files.  Environment variable settings are
ignored when these configuration files are read.  The currently
recognised variables are:
.TP
.B PLOTCHANGELOG_OPTIONS
This is a space-separated list of options to always use, for example
\fB\-l \-b\fP.  Do not include \fB\-g\fP or \fB\-\-gnuplot\fP among this list as it
may be ignored; see the next variable instead.
.TP
.B PLOTCHANGELOG_GNUPLOT
These are
.B gnuplot
commands which will be prepended to any such commands given on the
command line.
.SH "SEE ALSO"
.BR devscripts.conf (5)
.SH AUTHOR
Joey Hess <joey@kitenet.net>
